home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 3 / BBS in a box - Trilogy III.iso / Files / Prog / U-Z / VideoToolBox Folder / VideoToolboxSources / Luminance.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-12-31  |  10.8 KB  |  234 lines  |  [TEXT/KAHL]
  1. /*
  2. Luminance.h
  3. This is the include file for Luminance.c and ReadLuminanceRecord.c
  4. Copyright 1989,1990,1991,1992 (c) Denis G. Pelli 
  5. HISTORY:
  6. 9/18/90    dgp    Changed all instances of "v" to "V". The final version of the Pelli
  7.             & Zhang (1991) manuscript refers to a nominal voltage v; this file
  8.             now refers to the "equivalent number" V; they are related by V=255*v.
  9.             To avoid "breaking" all the old LuminanceRecord.h files, I've 
  10.             introduced a #define that converts vMin & vMax to VMin & VMax. However,
  11.             this is a temporary fix. I'll probably remove the define in a few months,
  12.             so you should still update any old calibration files, either by editing,
  13.             replacing "vM" by "VM" or by redoing the calibration.
  14. 9/24/90    dgp    Added screen & date. Renamed nBackground to VBackground.
  15.             Renamed index to lastIndex.
  16. 9/28/90    dgp    Renamed lastIndex to latestIndex. Spruced up some of the comments.
  17. 10/31/90 dgp Added the conditional FAST_LUMINANCE. Setting it to 1 (true) makes
  18.             SetLuminancesAndRange() run twice as fast, by using fixed point
  19.             arithmetic instead of doubles. Setting it to 0 (false) causes the
  20.             same code to be compiled to use doubles. Note that the prototypes of
  21.             some internal functions (names beginning with underscore) are conditional
  22.             on FAST_LUMINANCE.
  23. 11/6/90 dgp Replaced Milli by Fixed. 
  24. 11/8/90 dgp    Eliminated gamma slope table shiftedLSlope[] since the speed-up it offered
  25.             was too small to measure.
  26. 7/30/91    dgp    Added prototype for ReadLuminanceRecord().
  27. 8/4/91    dgp    Change ReadLuminanceRecord() to return type int.
  28. 8/5/91    dgp    Trying to compile under MPW C 3.2 uncovered a name-space conflict.
  29.             The MPW C 3.2 CType.h header file defines _L as a preprocessor constant,
  30.             whereas Luminance.h uses it as a field of the luminanceTable structure,
  31.             and as a parameter name.
  32.             The THINK C 4.05 ctype.h header file names the same constant __LOWR,
  33.             which of course doesn't conflict. The obvious solution would be to
  34.             change MPW's CType.h _L to _LOWR, but that would compromise portability.
  35.             I decided not to change _L in Luminance.h and Luminance.c,
  36.             because it would be hard to do that in a way that wouldn't compromise 
  37.             the readability of the code. However, I did do a quick hack, 
  38.             about ten lines below, that redefines _L as an enum, which solves the
  39.             problem, provided CType.h is included before Luminance.h in files that
  40.             need to explicitly access _L. In fact _L is intended for use
  41.             only by the routines that are in Luminance.c, so I suspect the
  42.             problem is solved.
  43. 12/17/92    dgp Removed obsolete support for THINK C 4. 
  44. 12/21/92 dgp Added dacSize and leftShift.
  45. */
  46.  
  47. #pragma once        /* suppress multiple inclusions of this file */
  48. #ifndef _LUMINANCE_    /* suppress multiple inclusions of this file */
  49. #define _LUMINANCE_
  50.  
  51. #include <QuickDraw.h>
  52. #include <Sound.h>
  53.  
  54. /*
  55. The following trickery redefines the MPW C 3.2 CType.h define constant
  56. _L as an enum, so that it won't conflict with the use of _L as a parameter name or
  57. structure field.
  58. */
  59. #ifdef _L
  60.     enum{____L=_L};
  61.     #undef _L
  62.     enum{_L=____L};
  63. #endif
  64.  
  65. /* These 3 #defines are a temporary fix, to allow use of old LuminanceRecord.h files */
  66. #define vMin VMin
  67. #define vMax VMax
  68. #define nBackground VBackground
  69.  
  70. /* LINEAR_V_DOMAIN is the maximum interval in V over which the gamma function is
  71. to be assumed linear by LToV(). The value 4 gives almost the same accuracy as 1, yet
  72. results in SetLuminances() on a Mac II taking only 29 ms instead of 50 ms. 
  73. See _LToV() in Luminance.c  for more information. */
  74.  
  75. #define MACINTOSH    1        /* set to 0 to use on any other computer */
  76. #define LINEAR_V_DOMAIN 4    /* see above */
  77. #define FAST_LUMINANCE 1    /* 1 for Fixed math (twice as fast), 0 for double math */
  78. #define DACS 3                /* number of digital-to-analog converters that we support */
  79. #define COLORS 256            /* size of ColorSpec table */
  80. #define MAX_COEFFICIENTS 9    /* polynomial fit */
  81. #define LUMINANCES_IN_TABLE 128    /* size of gamma table */
  82.  
  83. #if FAST_LUMINANCE
  84.     #include <ToolUtils.h>    /* prototypes for FixMul etc. */
  85. #endif
  86.  
  87. typedef struct{
  88.     ColorSpec table[COLORS];    /* a table of values destined for the clut */
  89. } Clut;
  90.  
  91. enum {Michelson,Weber};    /* contrastType */
  92.  
  93. typedef struct {
  94.     short exists;    /* set to luminanceSet once this table has been initialized */
  95.     short latestIndex;/* last-used index of LR.L._L[] is good place to start search */
  96.     #if FAST_LUMINANCE
  97.         Fixed _VMin;    /* bounds monotonic part of domain of gamma function */
  98.         Fixed _VMax;    /* bounds monotonic part of domain of gamma function */
  99.         Fixed _dV;        /* V = _VMin,_VMin+_dV,_VMin+2dV,_VMin+3dV, . . . ,_VMax */
  100.                         /* _dV=(_VMax-_VMin)/(LUMINANCES_IN_TABLE-1) */
  101.         Fixed _L[LUMINANCES_IN_TABLE];
  102.         long LShift;    /* bit shift to be applied to luminance differences */
  103.     #else
  104.         double _VMin;    /* bounds monotonic part of domain of gamma function */
  105.         double _VMax;    /* bounds monotonic part of domain of gamma function */
  106.         double _dV;        /* V = _VMin,_VMin+_dV,_VMin+2dV,_VMin+3dV, . . . ,_VMax */
  107.                         /* _dV=(_VMax-_VMin)/(LUMINANCES_IN_TABLE-1) */
  108.         double _L[LUMINANCES_IN_TABLE];
  109.     #endif
  110. } luminanceTable;
  111.  
  112. typedef struct {    /* "table" MUST be the first thing in the structure! */
  113.     ColorSpec table[COLORS];/* a table of values destined for the clut */
  114.     short dacSize;        /* bits */
  115.     short leftShift;    /* bit shift of V to produce 16 bit value=16-dacSize */
  116.     short VMin,VMax;    /* lowest and highest DAC values allowed: 0 and 255 */
  117.     double LMin,LMax;    /* luminances at VMin & VMax */
  118.     double LBackground;    /* the background luminance used during luminance calibration */
  119.     short VBackground;    /* the background number used during luminance calibration */
  120.     short screen;        /* device=GetScreenDevice(LR.screen); */
  121.     char *id;            /* make, model, and serial number of monitor */
  122.     char *name;            /* informal name of monitor */
  123.     char *date;            /* when calibrated */
  124.     char *notes;        /* description of calib conditions: who & how */
  125.     double dpi;            /* pixels per inch */
  126.     double Hz;            /* frames per second */
  127.     char *units;        /* Luminance units, e.g. "cd/m^2" */
  128.     long coefficients;    /* the number of coefficients, not more than MAX_COEFFICIENTS, */
  129.                         /*    usually 9, giving an 8th-order polynomial, */
  130.     double p[MAX_COEFFICIENTS];
  131.                         /* coefficients of a polynomial in value V, yielding L in cd/m^2 */
  132.     double polynomialError;    /* RMS error of polynomial fit */
  133.                         /* L(V)=p[0]+p[1]*V+p[2]*V*V+ . . . ±polynomialError */
  134.     double q[3];        /* coefficients of a quadratic polynomial in V */
  135.     double quadraticError;    /* RMS error of quadratic fit */
  136.                         /* L(V)=q[0]+q[1]*V+q[2]*V*V±quadraticError */
  137.     double power[4];    /* coefficients of a power law fit */
  138.     double powerError;    /* RMS error of power law fit */
  139.                         /* L(V)=power[0]+Rectify(power[1]+power[2]*V)^power[3]±powerError */
  140.                         /* Rectify(x)=x if x≥0, Rectify(x)=0 if x<0 */
  141.                         /* Pelli & Zhang (1991) Eqs.9&10 use symbols: */
  142.                         /* v=V/255, alpha=power[0], beta=power[1], kappa=power[2]*255, */
  143.                         /* gamma=power[3] */
  144.     double fixedPower[4];    /* coefficients of a power law fit, with fixed exponent */
  145.     double fixedPowerError;    /* RMS error of power law fit */
  146.                         /* L(V)=fixedPower[0]+Rectify(fixedPower[1]+fixedPower[2]*V)^fixedPower[3]±fixedPowerError */
  147.     double r,g,b;        /* voltage gains for the three pathways. r+g+b=1. All must be ≥0. */
  148.     double gainAccuracy;/* possible error in r,g,b */
  149.     double gm;            /* The monitor's contrast gain. The Michelson contrast produced by
  150.                             a small Δv at the background luminance is c=gm*Δv */
  151.     /* The rest of the parameters are for temporary storage by SetLuminanceRange() */
  152.     double lowLuminance;    /* the bottom of the range */
  153.     double highLuminance;    /* the top of the range */
  154.     short rangeSet;            /* a check that the range really has been set */
  155.     short dacs;                /* the number of dacs with nonzero gain, usually 1 or 3 */
  156.     short fixed;            /* the number of dacs whose value will be fixed for this range */
  157.     short dac[DACS];        /* which dac corresponds to each gain, r=0,g=1,b=2 */
  158.     double gain[DACS];        /* the ordered normalized gains of the Video Attenuator */
  159.     double VHalfStep;        /* half a step of the finest dac */
  160.     double VFixed;            /* the value produced by the fixed dacs */
  161.     double LOffset;            /* a small shift of the requested luminance range */
  162.     double tolerance;        /* the luminance error corresponding to half 
  163.                                 a step of the coarsest of the variable dacs */
  164.     #if FAST_LUMINANCE
  165.         Fixed _gain[DACS];
  166.         Fixed _VHalfStep;
  167.         Fixed _VFixed;
  168.         Fixed _LOffset;
  169.         Fixed _tolerance;
  170.     #else
  171.         double _gain[DACS];
  172.         double _VHalfStep;
  173.         double _VFixed;
  174.         double _LOffset;
  175.         double _tolerance;
  176.     #endif
  177.     RGBColor rgb;            /* cache the values of the fixed DACs */
  178.     luminanceTable L;
  179. } luminanceRecord;
  180.  
  181. enum {luminanceSet=12345};    /* a unique value that we can check for later */
  182.  
  183. /* Luminance.c */
  184. double SetLuminance(GDHandle device,luminanceRecord *LP
  185.     ,int theEntry,double luminance
  186.     ,double lowLuminance,double highLuminance);
  187. double SetLuminances(GDHandle device,luminanceRecord *LP
  188.     ,int firstEntry,int lastEntry
  189.     ,double firstLuminance,double lastLuminance);
  190. double SetLuminancesAndRange(GDHandle device,luminanceRecord *LP
  191.     ,int firstEntry,int lastEntry
  192.     ,double firstLuminance,double lastLuminance
  193.     ,double lowLuminance,double highLuminance);
  194. void LoadLuminances(GDHandle device, luminanceRecord *LP,
  195.     int firstEntry, int lastEntry);
  196. void IncrementLuminance(GDHandle device,luminanceRecord *LP,int theEntry);
  197. double GetLuminance(GDHandle device,luminanceRecord *LP,int theEntry);
  198. double GetV(GDHandle device,luminanceRecord *LP,int theEntry);
  199. double VToL(luminanceRecord *LP,double V);
  200. double LToV(luminanceRecord *LP,double L);
  201. double LToVFormulaic(luminanceRecord *LP,double L);
  202. double LToL(luminanceRecord *LP,double L);
  203.  
  204. /* The following routines are primarily for internal use. */
  205. #if FAST_LUMINANCE
  206.     void _SetLuminance(luminanceRecord *LPtr,int theEntry,Fixed _luminance);
  207.     Fixed _Tolerance(luminanceRecord *LP,Fixed _luminance);
  208.     void _SetLuminances(luminanceRecord *LP,int first,int last
  209.         ,Fixed _firstL,Fixed _dL64,Fixed _firstV,Fixed _lastV);
  210.     Fixed _VToL(luminanceRecord *LP,Fixed _V);
  211.     Fixed _LToV(luminanceRecord *LP,Fixed _L);
  212. #else
  213.     void _SetLuminance(luminanceRecord *LPtr,int theEntry,double _luminance);
  214.     double _Tolerance(luminanceRecord *LP,double _luminance);
  215.     void _SetLuminances(luminanceRecord *LP,int first,int last
  216.         ,double _firstL,double _dL8,double _firstV,double _lastV);
  217.     double _VToL(luminanceRecord *LP,double _V);
  218.     double _LToV(luminanceRecord *LP,double _L);
  219. #endif
  220. double SetLuminanceRange(luminanceRecord *LP
  221.     ,double lowLuminance,double highLuminance);
  222. double VToLPower(luminanceRecord *LP,double V);            /* use VToL() instead */
  223. double VToLPolynomial(luminanceRecord *LP,double V);    /* use VToL() instead */
  224. double LToVPower(luminanceRecord *LP,double L);            /* use LToV() instead */
  225. double LToVPolynomial(luminanceRecord *LP,double L);    /* use LToV() instead */
  226. double LToVQuadratic(luminanceRecord *LP,double L);        /* use LToV() instead */
  227.  
  228. /* ReadLuminanceRecord.c */
  229.  
  230. int ReadLuminanceRecord(char *filename,luminanceRecord *LP,int echo);
  231.  
  232. #endif _LUMINANCE_
  233.  
  234.